home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 301-325 / disk_309 / bind / bind.doc < prev    next >
Text File  |  1992-05-06  |  10KB  |  301 lines
  1. Bind - Binding (glue) library builder
  2.  
  3. Version 1.2 - 31-Dec-89
  4.  
  5.  
  6. Overview
  7. --------
  8.  
  9. This program takes a standard .fd (function definition) file and
  10. generates a binding library for the functions defined in the .fd file.
  11. The bindings are generated based on a set of rules for a target compiler
  12. defined in a file called "bindfile".  These rules specifiy which
  13. registers need to be preserved, how the arguments are passed on the
  14. stack, and the syntax to call an assembler and a librarian.
  15.  
  16. Unlike similar programs, Bind actually generates a linkable library instead
  17. of just a bunch of assembly files and a makefile.  It does this by running
  18. an assembler and librarian specified for a given set of rules in the
  19. bindfile.
  20.  
  21.  
  22. Requirements
  23. ------------
  24.  
  25. Bind requires arp.library v39+ (release 3) to function.
  26.  
  27.  
  28. New stuff
  29. ---------
  30.  
  31. Version 1.2 - 10-Dec-89
  32.  
  33.     Now can function for libraries that don't have a fixed Base pointer
  34.     (like cia.resource) (no ##base line).  In such cases, it assumed
  35.     that A6 is passed to the glue function as one of the arguments.
  36.  
  37.     Also now uses _LVO symbols instead of negative numbers in assembly
  38.     glue modules.  This should make the assembly output more useful.
  39.  
  40.  
  41. Version 1.1 - 9-Jul-89
  42.  
  43.     This version of Bind was more or less made necessary because v1.0
  44.     choked on the iffparse_lib.fd function arguments.  Bind now correctly
  45.     deals with register argument lists and is much more bullet-proof than
  46.     it previously was.
  47.  
  48.     The zlib program has been removed for this version since the ARP Join
  49.     command can be used instead.  Since Bind requires ARP, you should have
  50.     already have the ARP Join command.
  51.  
  52.  
  53. Arc File Contents
  54. -----------------
  55.  
  56.     Bind    -- The Bind program
  57.  
  58.     Bind.doc    -- This file
  59.  
  60.     bindfile    -- A sample bindfile containing rules for Aztec C (small
  61.            code/data and large code/data version) and Lattice C.
  62.            The Lattice C rules should work for any language that
  63.            uses the amiga.lib supplied by C=.
  64.  
  65.     misc_res.fd -- An .FD file for the Amiga's misc.resource.  According
  66.            to the the RKM manuals, this resource is supposed to be
  67.            called only from assembly.  I can see no good reason for
  68.            this other than that no one ever made any glue routines
  69.            for it.  Now you can make your own using Bind.
  70.  
  71.  
  72. Usage
  73. -----
  74.  
  75. The syntax for Bind is:
  76.  
  77.     Bind [opts] <.fd file>
  78.  
  79.     <.fd file> - name of the function definition file to use as a
  80.          source.  The ".fd" portion may be left off of the name.
  81.          The output library name is derived from the portion of
  82.          the .fd file to the left of the period (e.g.
  83.          midi_lib.fd will generate midi_lib.lib)
  84.  
  85.     opts:
  86.     -a    generate assembly only
  87.     -c    generate object modules only
  88.     -f<s>    specify alternate bindfile
  89.     -o<s>    specify output library name
  90.     -r<s>    specify rule name
  91.     -w<s>    specify work directory (default=CCTEMP env. variable)
  92.  
  93.  
  94.  
  95. A library is built by first generating an object module for each binding
  96. routine and an LVO definition module.  Each module is created by writing
  97. an assembly file to the work directory and then assembling it.    Once all
  98. the object modules are generated they are collected into a library.
  99. Temporary files (assembly and object) are deleted from the work
  100. directory as soon as they are no longer needed.  The actual invocations
  101. for the assembler and librarian depend on the selected set of rules.
  102.  
  103. Binding rules are defined in a "bindfile".  By default this file is
  104. called bindfile and resides in the current directory or the s:
  105. directory.  An alternate bindfile may be specified with the -f switch.
  106. A bindfile contains entries for target compilers.  Each entry contains
  107. rule definitions that specify how to build a binding routine for the
  108. target compiler.  The syntax is as follows:
  109.  
  110. <target>:
  111.     <rule key> = <value>
  112.     .
  113.     .
  114.     .
  115.     <rule key> = <value>
  116.  
  117. <target>:
  118.     <rule key> = <value>
  119.     .
  120.     .
  121.     .
  122.     <rule key> = <value>
  123.  
  124.     .
  125.     .
  126.     .
  127.  
  128.  
  129. The target name can contain any name but must not contain embedded
  130. spaces.  It should begin in the first column and be terminated with a
  131. colon.    Target name matching is case insensitive.
  132.  
  133. Rule keys must be preceded with white space and spelled exactly as
  134. follows (case is not significant).  They may be placed in any order
  135. within a rule set.
  136.  
  137.     Comment = <comment>
  138.  
  139.     An optional comment string to be placed in assembly files (only
  140.     visible if the -a switch is used) and the file comment for the
  141.     output library (visible with the List command).  The default is the
  142.     rule name.
  143.  
  144.  
  145.     StackOffset = <offset>
  146.  
  147.     Specifies how many bytes preceded arguments in the stack frame when
  148.     the routine first becomes active.  If nothing is pushed on the
  149.     stack between the arguments and the return location (pushed by jsr)
  150.     then <offset> would be 4.  This depends very heavily on how the
  151.     target compiler calls routines.  The default value is 4.
  152.  
  153.  
  154.     SaveRegs = <register set>
  155.  
  156.     This specifies the registers that the compiler expects to have
  157.     preserved.  Use a standard 68000 MOVEM register set here (e.g.
  158.     d2-d7/a2-a5).  The default is to preserve d2-d7/a2-a6.    Currently
  159.     you are not allowed to preserve D0 or A7 this way.  D0 is where
  160.     return values from placed by standard Kernal routines.    A7 is the
  161.     stack pointer and is automatically preserved.
  162.  
  163.  
  164.     Assembler = <asm syntax>
  165.  
  166.     Specifies the name of the assembler to use and its syntax.  Two
  167.     string substitutions are performed here.
  168.  
  169.         $A - gets replaced by the name of the assembly file
  170.          generated by Bind.
  171.  
  172.         $O - gets replaced by the name of the object module that
  173.          should be produced by the assembler.
  174.  
  175.     (e.g. as $A -o $O)  Bind generates assembly files suffixed with
  176.     .asm and expects object files to suffixed by .o.  These suffixes
  177.     are supplied with the $a and $o string substitutions.
  178.  
  179.     The assembler used should be capable of generating a
  180.     non-zero return code on failure in order to shut down Bind.
  181.     Both Aztec's as and MCC's assem behave well.
  182.  
  183.     The assembler is loaded using the ARP SyncRun() function so that
  184.     the current path will be searched in order to find the assembler.
  185.  
  186.     The default is no assembler.  This will not permit you to make
  187.     anything other than assembly files.
  188.  
  189.  
  190.     Librarian = <lb syntax>
  191.  
  192.     Specifies the name of the librarian to use and its syntax.  Two
  193.     string substitutions are performed here.
  194.  
  195.         $L - is replaced by the selected name of the output library.
  196.  
  197.         $O - is replaced by the entire list of object modules to
  198.          place in the library.
  199.  
  200.     (e.g. lb $L $O)  By default Bind will generate a library name based
  201.     on the .fd file name (e.g. midi_lib.fd becomes midi_lib.lib).  You
  202.     can select another output library name using the -o option.
  203.  
  204.     As with the assembler, the librarian should be capable of
  205.     generating a non-zero return code on failure in order.    Aztec's lb
  206.     utility, and the ARP Join command all behave this way.
  207.  
  208.     To generate an Amiga object module library (ALink/BLink
  209.     compatible), use the ARP Join command as the Librarian:
  210.  
  211.         Librarian = join $O as $L
  212.  
  213.     Amiga object module libraries appear to be simply a concatenation
  214.     of the constituent object modules so Join can be used to make one
  215.     out of object files.  NOTE: The AmigaDOS Join command can't be used
  216.     for this since it is limited to joining no more than 15 files.
  217.  
  218.     The default is no librarian.  This will prevent you from
  219.     going beyond the object module stage.
  220.  
  221.  
  222. Comments may be placed in the bindfile if they are preceeded with a
  223. pound sign (#) in the first column (like makefile comments).  Also,
  224. blank lines are considered comments.
  225.  
  226. There is a sample bindfile contained in the .arc file containing rules for
  227. Aztec C and Lattice C.    The Lattice C rules may be applicable to other
  228. languages as well since they conform to the Amiga register preservation
  229. rules.
  230.  
  231.  
  232. Work files
  233. ----------
  234.  
  235. Work files are placed in the "work directory".  The work directory is
  236. determined in one of two ways.    If none is specified, the directory
  237. associated with the environment variable CCTEMP is used (this is set by
  238. either the Manx or ARP Set command or the C= or ARP SetEnv command).  You
  239. may override this by using the -w switch to specify any directory.  The
  240. default is the current directory.
  241.  
  242. Work files are automatically deleted when they are no longer needed or
  243. when the program fails or is aborted using Control-C.
  244.  
  245.  
  246. The options
  247. -----------
  248.  
  249. -a  Causes Bind to stop after generating the assembly code for the
  250.     bindings.  They appear in the work directory.
  251.  
  252. -c  Causes Bind to assemble the modules that it generates but leave just
  253.     the object modules without making a library.
  254.  
  255. -f  Allows you to specify some other file to use as a bindfile.  The
  256.     default bindfile may exist in the current directory or in the s:
  257.     directory.
  258.  
  259. -o  Allows you to specify another name for the output library.    The default
  260.     is made by replacing .fd in the source file name with .lib.  The
  261.     library name you specify here will be suffixed with .lib unless you
  262.     specify some other suffix.
  263.  
  264.     A file comment is set for the output library indicating which rules
  265.     were used to create it.  The Comment bindfile rule is used for the file
  266.     comment if present, otherwise the rule name is used.
  267.  
  268. -r  Specifies a rule name.  The default is to use the first rule in the
  269.     bindfile.
  270.  
  271. -w  Specifies an alternate work directory.  The default is the value of the
  272.     CCTEMP environment variable (set by Set or SetEnv).
  273.  
  274.  
  275. Tech info
  276. ---------
  277.  
  278. The program was compiled using Aztec C3.6a.  Everything described works. At
  279. the very least this can be used to generate bindings for Aztec C (any
  280. model) and Lattice C.
  281.  
  282. Compilers that don't use A7 for a stack, don't return values in D0, pack
  283. the arguments in reverse order, or require that the bindings pop arguments
  284. off the stack are not currently supported by Bind.  This may change if
  285. there is demand for this and the appropriate technical data is available.
  286.  
  287. .fd files are not described in this document.
  288.  
  289.  
  290. Last words
  291. ----------
  292.  
  293. Bind is copyright (c) 1987-89 by Pregnant Badger Software, but feel free to
  294. distribute it for non-profit.
  295.  
  296.     Bill Barton
  297.  
  298.     Bix: peabody
  299.     plink: peabody
  300.  
  301.